Skip to content

fix(markdown): render map and scalar declarations and correct stereotypes - #322

Open
chaitijain593-prog wants to merge 1 commit into
accordproject:mainfrom
chaitijain593-prog:fix/markdown-declarations
Open

chaitijain593-prog wants to merge 1 commit into
accordproject:mainfrom
chaitijain593-prog:fix/markdown-declarations

Conversation

@chaitijain593-prog

Copy link
Copy Markdown
Contributor

Closes #321

Fixes missing map and scalar declaration rendering in generated Markdown documentation, ensures accurate stereotypes for assets, participants, transactions, and events, and corrects a typo in table headers.

Changes

  • Implemented visitMapDeclaration to render map name, description, key type, and value type table.
  • Implemented visitScalarDeclaration to render scalar name, description, type, default value, and validation constraints.
  • Overrode visitAssetDeclaration, visitParticipantDeclaration, visitTransactionDeclaration, and visitEventDeclaration so that entity headings accurately reflect their kind instead of defaulting to (Concept).
  • Corrected table header typo | Contraints | to | Constraints |.
  • Added a full unit test suite with 19 tests under test/codegen/fromcto/markdown/markdownvisitor.js.
  • Updated codegen test snapshots for markdown output.

Flags

  • None. All existing verification and linting tests pass cleanly.

Related Issues

Author Checklist

  • Ensure you provide a DCO sign-off for your commits using the --signoff option of git commit.
  • Vital features and changes captured in unit and/or integration tests
  • Commits messages follow AP format
  • Extend the documentation, if necessary
  • Merging to main from fork:branchname

…ypes (accordproject#321)

Signed-off-by: chaitijain593 <chaitijain593@gmail.com>
@mira-accord-project

Copy link
Copy Markdown

Thank you for this contribution, and welcome to Accord Project.

The markdown visitor now renders map and scalar declarations, which were previously left out. It also uses the right stereotype for assets, participants, transactions and events, and fixes the Constraints header typo. Unit tests and snapshot updates are included.

The change is large, so a maintainer may ask for it to be split into smaller pull requests. We have requested reviews from the codegen maintainers. The CI runs are waiting for a maintainer to approve them before they start, which is normal for a first contribution.

Drafted by an Accord Project agent, reviewed by a maintainer.

@mira-accord-project mira-accord-project Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this. The markdown output now covers maps and scalars, assets, participants, transactions and events get their own headings, and the Contraints typo is fixed. The new unit tests and the snapshot changes all follow from the fix. Nothing here is blocking. Before merge, please fix how falsy scalar defaults are handled (0, 0.0, false) and add a test for that case. The map type-name point is optional. Because the change is large, a maintainer's approval is also needed.

Nothing blocking; some suggestions below. Findings: 1 should-fix, 1 nit.


Automated review by Mira, an Accord Project agent, at 5e46a31. Findings are labelled blocking, should-fix or nit; a maintainer makes the final call.

}
}

const defaultValue = scalarDeclaration.getDefaultValue?.() ? `<code>${scalarDeclaration.getDefaultValue()}</code>` : '';

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should-fix · correctness

visitScalarDeclaration uses a truthiness test to decide whether to print the default value: scalarDeclaration.getDefaultValue?.() ? ... : ''. ScalarDeclaration.getDefaultValue() returns null when no default is set, and otherwise returns the value, which can be 0, 0.0 or false. So scalar Count extends Integer default 0 or scalar Flag extends Boolean default false gets an empty Default Value cell, as if it had no default. Suggested fix: const dv = scalarDeclaration.getDefaultValue?.(); const defaultValue = dv !== null && dv !== undefined ? ${dv} : '';. Please also add a unit test with a falsy default (e.g. getDefaultValue.returns(0)), since the current scalar test only covers a non-empty string default.

parameters.fileWriter.writeLine(0, descriptionDecorator?.getArguments()[0] || '');
}

const keyType = mapDeclaration.getKey().getType();

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit · design

Map key and value types are rendered with getType(), which gives the short name: the snapshot shows <code>Employee</code> and <code>SSN</code>. Field types in the same document are fully qualified (org.acme.hr@1.0.0.Employee). For a map whose key or value type is imported, readers can't tell which namespace it comes from. Consider resolving non-primitive names to their fully qualified form, for example through the model file's getFullyQualifiedTypeName, so maps match the class tables.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug(markdown): MarkdownVisitor omits map and scalar declarations and mislabels declaration types

1 participant